update mpt docs for permissioneddomains #3251

oeggert · 2025-08-20T21:47:26Z

Updated MPTTokenIssuanceCreate and MPTokenIssuanceSet transaction docs to include DomainID field. Also added additional error codes.

Documents changes to MPT that are gated by Single Asset Vaults: XRPLF/rippled#5509

mDuo13

To be clear, this is set to go into rippled version 3.0.0, not version 2.6.0 which is the next planned release?

docs/references/protocol/transactions/types/mptokenissuancecreate.md

docs/references/protocol/transactions/types/mptokenissuanceset.md

Bronek · 2025-08-21T08:25:00Z

To be clear, this is set to go into rippled version 3.0.0, not version 2.6.0 which is the next planned release?

Yes. Although the changes are in release 2.6.0, they are amendment gated by SingleAssetVault which, in release 2.6.0 is not supported hence cannot be voted (and enabled). This means the changes will not be enabled until after 3.0.0 release (which will flip the Supported flag) and obviously, after the amendment has been voted.

docs/references/protocol/transactions/types/mptokenissuancecreate.md

docs/references/protocol/transactions/types/mptokenissuanceset.md

docs/references/protocol/transactions/types/mptokenissuancecreate.md

docs/references/protocol/transactions/types/mptokenissuanceset.md

mDuo13 · 2025-11-04T21:33:34Z

docs/references/protocol/transactions/types/mptokenissuanceset.md

+| `tecNO_DELEGATE_PERMISSION` | You are attempting to use a delegate account with insufficient permissions to submit this transaction. |
+| `tecNO_DST`               | The account specified in the `Holder` field doesn't exist. |
+| `tecNO_PERMISSION`        | - The `lsfMPTCanLock` flag isn't enabled, but you are attempting to lock or unlock an MPT.<br>- The `SingleAssetVault` amendment is disabled and you're trying to modify a `DomainID` field. | 
+| `temMALFORMED`            | - You specified a `DomainID` and `Holder` value--only one can be set in a single transaction.<br>- You specified the same account for both `Acount` and `Holder`.<br>- The transaction isn't changing anything; it must either update a flag or modify the `DomainID`. |


temMALFORMED is a code that can occur for any transaction type.

Suggested change

| `temMALFORMED` | - You specified a `DomainID` and `Holder` value--only one can be set in a single transaction. - You specified the same account for both `Acount` and `Holder`. - The transaction isn't changing anything; it must either update a flag or modify the `DomainID`. |

Same comment in issuancecreate. I think it's helpful to explain how you'd malform this specific transaction.

mDuo13 · 2025-11-04T21:35:10Z

docs/references/protocol/transactions/types/mptokenissuancecreate.md

+| `temBAD_TRANSFER_FEE`     | The transfer fee specified is greater than the maximum allowed value of 50,000. |
+| `temDISABLED`             | The `MPTokensV1` amendment is disabled. You will also receive this error if you include a `DomainID` field in the transaction, but the `PermissionedDomains` and `SingleAssetVault` amendments are both disabled. |
+| `tecINSUFFICIENT_RESERVE` | The account creating the `MPTokenIssuance` ledger entry doesn't have enough XRP to meet the owner reserve. |
+| `temMALFORMED`            | - A non-zero transfer fee is set, but the `tfMPTCanTransfer` flag is _not_ set.<br>- The `DomainID` points to an invalid permissioned domain; you can also receive this error if you include a `DomainID` without setting the `tfMPTRequireAuth` flag.<br>- The `MPTokenMetadata` field is an invalid length (0 or exceeds 1024 bytes).<br>- The `MaximumAmount` field is 0 or exceeds 9,223,372,036,854,775,807 (2^63-1). |


temMALFORMED is one of the errors that can occur for any transaction type.

Suggested change

| `temMALFORMED` | - A non-zero transfer fee is set, but the `tfMPTCanTransfer` flag is _not_ set. - The `DomainID` points to an invalid permissioned domain; you can also receive this error if you include a `DomainID` without setting the `tfMPTRequireAuth` flag. - The `MPTokenMetadata` field is an invalid length (0 or exceeds 1024 bytes). - The `MaximumAmount` field is 0 or exceeds 9,223,372,036,854,775,807 (2^63-1). |

True, but I think it's helpful to explain what specifically you could be malforming to make it easier for someone to troubleshoot.

Maybe I could preface it with something like: "Besides generally malformed transactions, you can receive this error if ..."

There are infinite ways to creatively malform a transaction, but if there are common uses or patterns that hit the specific cases described here, then I agree it makes sense to note it here with a preface like you suggested.

mDuo13 · 2025-11-25T23:44:57Z

docs/references/protocol/transactions/types/mptokenissuancecreate.md

+| `temBAD_TRANSFER_FEE`     | The transfer fee specified is greater than the maximum allowed value of 50,000. |
+| `temDISABLED`             | The `MPTokensV1` amendment is disabled. You will also receive this error if you include a `DomainID` field in the transaction, but the `PermissionedDomains` and `SingleAssetVault` amendments are both disabled. |
+| `tecINSUFFICIENT_RESERVE` | The account creating the `MPTokenIssuance` ledger entry doesn't have enough XRP to meet the owner reserve. |
+| `temMALFORMED`            | - A non-zero transfer fee is set, but the `tfMPTCanTransfer` flag is _not_ set.<br>- The `DomainID` points to an invalid permissioned domain; you can also receive this error if you include a `DomainID` without setting the `tfMPTRequireAuth` flag.<br>- The `MPTokenMetadata` field is an invalid length (0 or exceeds 1024 bytes).<br>- The `MaximumAmount` field is 0 or exceeds 9,223,372,036,854,775,807 (2^63-1). |


There are infinite ways to creatively malform a transaction, but if there are common uses or patterns that hit the specific cases described here, then I agree it makes sense to note it here with a preface like you suggested.

mDuo13 · 2025-11-25T23:59:28Z

docs/references/protocol/transactions/types/mptokenissuancecreate.md

 | Field             | JSON Type            | [Internal Type][] | Required? | Description |
 |:------------------|:---------------------|:------------------|:----------|:------------|
 | `AssetScale`      | Number               | UInt8             | No        | Where to put the decimal place when displaying amounts of this MPT. More formally, the asset scale is a non-negative integer (0, 1, 2, …) such that one standard unit equals 10^(-scale) of a corresponding fractional unit. For example, if a US Dollar Stablecoin has an asset scale of _2_, then 1 unit of that MPT would equal 0.01 US Dollars. This indicates to how many decimal places the MPT can be subdivided. If omitted, the default is 0, meaning that the MPT cannot be divided into smaller than 1 unit. |
+| `DomainID`        | String - [Hash][]    | UInt256           | No        | The ledger entry ID of a permissioned domain that grants access to the MPT. You must set the `tfMPTRequireAuth` flag to use permissioned domains.<br>{% amendment-disclaimer name="PermissionedDomains" /%}<br>{% amendment-disclaimer name="SingleAssetVault" /%} |


You don't need   tags here, since the disclaimer already uses its own  tag.

Use "enable" instead of "set" for clarity when talking about flags. ("Set? To what?")

This is currently (as expected) throwing errors because the SingleAssetVault amendment isn't in the VHS data yet. We should make a note to come back and double-check this before merging to the master branch, closer to release—but it's not a blocker for merging to the rippled-3.0.0 branch.

Suggested change

| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. You must set the `tfMPTRequireAuth` flag to use permissioned domains. {% amendment-disclaimer name="PermissionedDomains" /%} {% amendment-disclaimer name="SingleAssetVault" /%} |

| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. You must enable the `tfMPTRequireAuth` flag to use permissioned domains. {% amendment-disclaimer name="PermissionedDomains" /%} {% amendment-disclaimer name="SingleAssetVault" /%} |

mDuo13 · 2025-11-26T00:05:24Z

docs/references/protocol/transactions/types/mptokenissuanceset.md


 | Field               | JSON Type            | [Internal Type][] | Required? | Description |
 |:--------------------|:---------------------|:------------------|:----------|-------------|
+| `DomainID`          | String - [Hash][]    | UInt256           | No        | The ledger entry ID of a permissioned domain that grants access to the MPT. An empy value or `0` will remove permissioned domain access management. Any accounts that lose access to the MPT because of `DomainID` updates--unless explicitly authorized by the MPT issuer--lose the ability to send or receive MPTs they already hold. The `tfMPTRequireAuth` flag must have been set in the `MPTokenIssuanceCreate` transaction to use permissioned domains.<br>{% amendment-disclaimer name="PermissionedDomains" /%}<br>{% amendment-disclaimer name="SingleAssetVault" /%} |


Typo ("empy")

Avoid future tense.

Use an actual emdash instead of two hyphens. (Here's one you can copy-paste: — ) Or better yet, avoid phrasing sentences with this type of interjection in the first place.

The description feels a little confusing about when you lose the ability to send or receive MPTs.

The phrase "permissioned domain access management" feels a little ambiguous or confusing, like it's controlling who has access to manage the domain itself, and I don't think it's defined anywhere in those exact terms. Either rephrase into simpler language or shorten this description and link to a better description on a concept page.

Rather than talk about the exact transaction flag from the create transaction, talk about the current state of the MPT issuance (among other reasons, maybe that flag is mutable).

Suggested change

| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. An empy value or `0` will remove permissioned domain access management. Any accounts that lose access to the MPT because of `DomainID` updates--unless explicitly authorized by the MPT issuer--lose the ability to send or receive MPTs they already hold. The `tfMPTRequireAuth` flag must have been set in the `MPTokenIssuanceCreate` transaction to use permissioned domains. {% amendment-disclaimer name="PermissionedDomains" /%} {% amendment-disclaimer name="SingleAssetVault" /%} |

| `DomainID` | String - [Hash][] | UInt256 | No | The ledger entry ID of a permissioned domain that grants access to the MPT. An empty value or `0` removes the permissioned domain from the MPT issuance so that only users who are explicitly approved by the issuer can send and receive the MPT. You can only set a `DomainID` if the MPT issuance has [**Require Auth**](/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens#transferability-controls) enabled.) {% amendment-disclaimer name="PermissionedDomains" /%} {% amendment-disclaimer name="SingleAssetVault" /%} |

Note, I opened #3392 since it feels like we need better documentation on how to create and use allow-listing with MPTs (concept/tutorial/code sample/etc.).

update mpt docs for permissioneddomains

f20f8c5

mDuo13 reviewed Aug 20, 2025

View reviewed changes

docs/references/protocol/transactions/types/mptokenissuancecreate.md Outdated Show resolved Hide resolved

docs/references/protocol/transactions/types/mptokenissuanceset.md Outdated Show resolved Hide resolved

Bronek reviewed Aug 21, 2025

View reviewed changes

docs/references/protocol/transactions/types/mptokenissuancecreate.md Outdated Show resolved Hide resolved

Bronek reviewed Aug 21, 2025

View reviewed changes

docs/references/protocol/transactions/types/mptokenissuanceset.md Outdated Show resolved Hide resolved

oeggert added 2 commits August 21, 2025 16:40

add reviewer suggestions

015f3ab

update error codes and amendment component

45e0809

oeggert requested a review from mDuo13 November 4, 2025 20:12

oeggert and others added 2 commits November 4, 2025 13:28

initialize 3.0 doc branch

864c412

Merge branch 'rippled-3.0.0' into sav-doc-updates

b9a0772

mDuo13 requested changes Nov 4, 2025

View reviewed changes

add @mDuo13 suggestions

1143443

oeggert requested a review from mDuo13 November 4, 2025 21:57

oeggert mentioned this pull request Nov 4, 2025

3.0 Release Doc Updates #3374

Draft

6 tasks

oeggert force-pushed the rippled-3.0.0 branch from 642ae4a to 682389e Compare November 25, 2025 23:16

mDuo13 requested changes Nov 26, 2025

View reviewed changes

	\| `DomainID` \| String - [Hash][] \| UInt256 \| No \| The ledger entry ID of a permissioned domain that grants access to the MPT. You must set the `tfMPTRequireAuth` flag to use permissioned domains.<br>{% amendment-disclaimer name="PermissionedDomains" /%}<br>{% amendment-disclaimer name="SingleAssetVault" /%} \|
	\| `DomainID` \| String - [Hash][] \| UInt256 \| No \| The ledger entry ID of a permissioned domain that grants access to the MPT. You must enable the `tfMPTRequireAuth` flag to use permissioned domains. {% amendment-disclaimer name="PermissionedDomains" /%} {% amendment-disclaimer name="SingleAssetVault" /%} \|

update mpt docs for permissioneddomains #3251

Are you sure you want to change the base?

update mpt docs for permissioneddomains #3251

Uh oh!

Conversation

oeggert commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mDuo13 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Bronek commented Aug 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mDuo13 Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

oeggert Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

mDuo13 Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

oeggert Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mDuo13 Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

mDuo13 Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

mDuo13 Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mDuo13 Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

mDuo13 Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

oeggert commented Aug 20, 2025 •

edited

Loading

oeggert Nov 4, 2025 •

edited

Loading

mDuo13 Nov 25, 2025 •

edited

Loading